## 
 # ###################################################################
 #  Vince's Additions - an extension package for Alpha
 # 
 #  FILE: "ElecCompletions Help"
 #                                    created: 00-05-19 16.44.50 
 #                                last update: 11/28/2001 {10:45:23 AM} 
 #  Author: Vince Darley
 #  E-mail: <vince@santafe.edu>
 #    mail: 317 Paseo de Peralta
 #          Santa Fe, NM 87501, USA
 #     www: <http://www.santafe.edu/~vince/>
 #  
 # Copyright (c) 1997-2000  Vince Darley
 # Some pieces pasted from Alpha-D mailing list responses.
 # ###################################################################
 ##


The idea with electric completions is to save you key strokes. When you hit
ctrl-tab Alpha tries to expand what you have just typed to give the rest of
what you want (the choice of ctrl-tab can be adjusted in the 
'Config->Special Keys' dialog).

If you want basic help/tutorial information, do the following: when 
you're in a mode for which you want a tutorial on electric completions,
select 'Completions Tutorial' from the 'Mode Prefs' menu.  Follow 
the instructions there.

You can modify the following preferences using the 
'Config->Preferences->Electrics' menu item:

	 useElectricMenu --- use electric template menu 
	 showElectricsInMenu --- show electric completions in menu 
	 showElectricKeysInMenu --- show electric key bindings in menu
	 modeSpecificElecTab --- use mode-specific electric tab 
	 electricTab --- use electric tab 
	 templateStopColor --- colour of template stops 
	 listPickIfMultExpds --- similarly for expansions 
	 ElectricFillers --- The format of the template stops:
	      0 = just use bullets
	      1 = use bullets but signal the name in the status window
	      2 = insert names into the window with the bullets
	      3 = insert names and highlight into the window with the bullets
	 maxTemplateNesting--- level of nesting we allow before clearing 

The electric menu contains a 'Templates' sub-menu, which contains global 
templates stored in the variable 'univ::MenuTemplates', and mode-specific
templates stored in variables ${mode}Templates.  The format of these 
variables is a list of names, which correspond to procedures when prepended 
with 'file::'.  You can add new items by using the menu item.

	  	Templates

Many of the routines in Vince's Additions allow you to insert templates for 
'for' loops, '\begin...\end environments', file headers, function comments, 
and even entire documents.  This section details the features of Vince's 
Additions which allow you to do that.  Here's an example of a 'for' template
in C++ mode (created just by typing 'for<ctrl-Tab>'):

	for (<init>;<test>;<increment>){
		<loop body>
	}
	

Once a template has been inserted, it will often contain a number of 
'place-markers' or 'template-stops' at each of which you will most likely 
wish to enter some text/code.  You can jump backwards and forwards amongst 
these stops using a set of key bindings.  You have a choice between two 
basic sets (you select using the 'Electric Bindings' dialog):

Function                Default binding             Alternative binding

Expand                  command-space               command-space
Next stop or indent     tab                         no binding
nth Stop                no binding                  control-tab
Complete or Tab         no binding                  tab
Next stop               no binding                  control-j
Clear all stops         shift-control-tab           shift-control-tab
Complete                control-tab                 no binding
Real tab                option-tab                  option-tab
Prev stop               shift-tab                   shift-control-j

Furthermore you can redefine any of these bindings using that same
dialog.

You have a choice between four different formats for the visual appearance 
of the template-stops.  They are usually signified by a bullet '', but 
more elaborate methods are supported.  These templates may be nested 
without any extra effort on your part.  Most of this code is contained in 
the file "betterTemplates.tcl", although all the bindings and initialisation 
are in "elecBindings.tcl".

Look at the new 'electric' menu for a list of these bindings, together 
with some other functions.

================================================================================

	  	Completions

I've now written a unified collection of procedures to address command 
completion, code indentation, electric-code generation, word completion and 
related facilities (incorporating my old TeX-reference completion for 
example). 

Here's a typical example from TeX mode, I type:

	for an explanation of this phenomenon,
	please refer to Fig<ctrl-Tab>
	
The <ctrl-Tab> signifies that Vince's Additions should try to complete the 
currently typed text.  In this case the completion is:

	for an explanation of this phenomenon,
	please refer to Figure~\ref{fig-
	
If I hit <ctrl-Tab> again, Vince's Additions tries to search for TeX 
'\labels' which begin with 'fig-' to insert the first such label
it finds into the text:

	for an explanation of this phenomenon,
	please refer to Figure~\ref{fig-heat-vs-time}
	
If this is the wrong one, I can keep hitting <ctrl-Tab> until I reach the 
correct completion:

	for an explanation of this phenomenon,
	please refer to Figure~\ref{fig-explanation}
	
Here's an example from C/C++ modes. I type 'for<ctrl-Tab>' and get:

	for (;;){
		
	}

This works at any current level of indentation, and the bullet marks '' 
are placemarkers.  You can just press 'Tab' (without 'ctrl') to jump from 
one to the next.

These facilities are activated as follows:

	Tab --- plain - either 'indent' or 'next template mark'
			ctrl   - complete the current text.
			opt   - insert a real tab.
						
So, pressing Tab by default will _not_ necessarily insert a tab, rather it 
will indent the current line of code to the correct indentation level to 
match the code around it.  

	  	  Types of completion


Control-Tab has a number of different meanings, which will be explained 
below.  Completions are listed in order of precedence.

	  	    User completion: 

all entries defined in the array 'userCompletions' are checked and inserted 
if appropriate.  This is useful to make 'vmd' turn into 'Vince Darley', or 
'www' into my home-page url, or ...
	
User completions are active in all modes, and take precedence over all 
other completion types.

	  	    Context sensitive completion: 

Context sensitive completions are mode dependent.  In some modes you 
can tell relatively easily from the context whether a particular 
'word' is a variable or procedure name or...  If different completion
procedures are useful for different types of word, then they are 
checked next.  For instance, in Tcl mode, a word beginning with '$',
or preceded by 'set' or 'global' is a variable name.  It should 
therefore be completed preferentially as a variable, rather than
being expanded as a command.  E.g. $str should normally not be
expanded to '$string ...' since it's clearly not the command 'string' 
that the user is trying to type.  

	  	    Command completion: 

For instance: type 'str<ctrl-tab>' and it is completed to 'string' (in Tcl 
mode).  If there are multiple possibilities then the longest unique prefix 
is inserted.
    
The available completions are mode dependent, and stored as a large string 
in the variable ${mode}cmds.  They must be stored alphabetically, and
be separated by whitespace.  THERE IS NO LONGER A NEED TO BEGIN AND
END THE LIST WITH WHITESPACE.

Here is the default value for Tcl mode:

	set Tclcmds { append array catch close concat continue elseif error
	for foreach format lindex lsearch lsort regexp regsub
	rename return string switch while }

	  	    Ensemble completion: 

type 'string co<ctrl-Tab>' and this is both completed to 'string compare' and 
an electric template is inserted for the arguments of this two part 
command.  Useful for any case in which the word before last is the command, 
and the word just before is part of a refinement of that command, in any 
situation for which a number of further arguments will be filled in.
	
	  	    Electric code template generation: 

type 'for<ctrl-tab>' and a complete template for code is generated (example 
for C mode):
	
	for (;;){
		
	}

You can move from one template mark '' to the next with, plain 'Tab' - 
I automatically sense whether a template insertion is in progress or
not and interpret tab accordingly.

These are again mode dependent. Each is stored individually as an element 
of the array ${mode}electrics, so, for instance the above electric code is 
generated by:

	set Celectrics(for) " (;;)\{\n\t\n\}\n"

Note how the bullets are double in the definition.  You can actually place 
an explanatory bit of text between pairs of bullets.  This is then used as 
a hint to the user:

	set Celectrics(for) " (start;test;increment)\{\n\tbody\n\}\n"

	  	    Class name completion: 

In C++ mode, when entering a class definition, the class name occurs 
multiple times.  To save entering all of these, this completion will
fill them all in for you.  It works like this: type 'class<ctrl-tab>'

	class <object name> : public <parent> {
	  public:
		<object name>(<args>);
		~<object name>(void);
	
	};
	

Now type the class name, say 'toaster', followed by <ctrl-tab>.  This
will result in:

	class toaster : public <parent> {
	  public:
		toaster(<args>);
		~toaster(void);
	
	};
	

i.e. each occurrence of the electric stop 'object name' has been 
filled in correctly.  This feature may be easily extended to more
complex examples.

	  	    TeX reference completion: 

type '\ref<ctrl-Tab>' and the command is automatically completed with the 
name of a nearby \label{}.  Repeated <ctrl-Tab> keypresses will cycle 
through all \label's.  Further, these commands chain together, so typing 
'\eqr<ctrl-Tab>' will complete the \eqref and continue to fill in a nearby 
label!

These were explained above.  Note that the reference completions can be 
instigated by command completion on, 'Fig' 'Chap' 'Eq.'  'Sec', ...  which 
insert the standard label prefix 'fig:' 'chap:' 'eq:' 'sec:' as 
appropriate.  If you complete with no prefix, then any label will match; if 
you have a prefix then only those which match will be suggested.

	  	    TeX citation completion.  

Type '\cite{Darley19<ctrl-Tab>' and the command is completed with a matching 
citation entry from one of your '.bib' database files.  If there are 
multiple possibilities, then you are prompted with a list from which to 
choose.  (Note: if you find the selection box a bit narrow, it is possible
to edit Alpha using ResEdit to increase its size).  Depending upon the
value of a TeX flag, the list can include the titles of each choice,
making it more obvious to you which is correct.

	  	    TeX environment completion: 

\begin{} \end{} pairs with synchronisation of the parameter, and template 
generation of the body.

You can complete '\begin<ctrl-Tab>' followed by 'equ<ctrl-Tab>' to the
following:

	\begin{equation}
		
		\label{eq:}
	\end{equation}
	

You have a choice between the double-completion, as above, or just typing
'\begin{equation}<ctrl-Tab>' which will do the job in one go.

Similar things work for 'itemize' 'enumerate' etc.  Of particular use
are the completions for 'figure' environments, from which you can enter
ordinary figures, floating figures, and a large number of sub-figure 
configurations (2 figures side-by-side, a block of 4,...).  For instance,
a handful of key-presses will give you this:

	\begin{figure}
		\centering
		\subfigure[subfig caption]{\label{fig:}%
			\includegraphics[width=\figstwo]{graphics file}}\goodgaptwo
		\subfigure[subfig caption]{\label{fig:}%
			\includegraphics[width=\figstwo]{graphics file}}\\
		\subfigure[subfig caption]{\label{fig:}%
			\includegraphics[width=\figstwo]{graphics file}}\goodgaptwo
		\subfigure[subfig caption]{\label{fig:}%
			\includegraphics[width=\figstwo]{graphics file}}%
		\caption[short caption for t.o.f.]{caption}
		\label{fig:}
	\end{figure}
	

For these to work, you must use the correct LaTeX packages (graphics, 
floatingfigure or subfigure as appropriate, although the code will 
automatically insert the correct 'usepackage' specifications for you if 
desired), and you may need the following definitions in your LaTeX 
preamble:

	\newlength{\goodspace}
	\newlength{\goodspacethree}
	\newlength{\goodspacefour}
	\newlength{\figstwo}
	\newlength{\figsthree}
	\newlength{\figsfour}
	
	\setlength{\goodspace}{\subfigtopskip+\subfigbottomskip}
	\setlength{\goodspacethree}{\goodspace}
	\setlength{\goodspacefour}{\goodspace*\real{0.6}}
	
	\newcommand{\goodgap}{\hspace{\goodspace}}
	\newcommand{\goodgaptwo}{\goodgap}
	\newcommand{\goodgapthree}{\hspace{\goodspacethree}}
	\newcommand{\goodgapfour}{\hspace{\goodspacefour}}
	
	\setlength{\figstwo}{(\linewidth-\goodspace)/2-1pt}
	\setlength{\figsthree}{(\linewidth-\goodspace *2)/3-1pt}
	\setlength{\figsfour}{(\linewidth-\goodspace *\real{1.8})/4-1pt}

These allow good alignment and spacing for most subfigure combinations
without the need for manual intervention.  

Some environments can contain an arbitrary number of items.  In this case, 
hitting 'shift-option-i' will add an item.  Here we turn this:

	\begin{description}
		\item[First one] here's the description
		
		\item[name] description
		
	\end{description}
	

into:

	\begin{description}
		\item[First one] here's the description
		\item[] 
		
		\item[name] description
		
	\end{description}
	

Similar entries work correctly for itemised, enumerated, aligned,... 
environments.

	  	    File-name completion:

Useful for Shel mode, this allows you to type a partial directory or 
filename and hit ctrl-Tab to have it extended as much as possible.

	  	    Tcl Variable Completion:

Tcl variables are often referenced with '$var' or just 'var' or '${var}'.  
You can complete between any of these types.  A local search for a match is 
done and the closest match inserted.  Again you can cycle through other 
matches with <ctrl-Tab>

	  	    Word Completion: 

if none of the above succeeded then the current word is completed to copy 
nearby words (variable names) in the file.  Again, repeated presses will 
cycle through other possibilities.

In any form of text in any mode, if no mode-specific completion matches, 
then any local word can match, complete and be cycled through as usual.

	  	  Template insertion

You'll notice in a lot of the above examples that bullets '' are inserted
into the text. In fact the user has a choice of four different levels of
interaction with the template insertion procedures. You can change this
using the universal preferences dialog (in the config menu). You can move
from one insertion point to the next using the 'tab' key; move backwards
with 'shift-tab'. If you don't like these key bindings, an alternative set
is available by a change in the universal preferences. You can also choose
the colour of the inserted bullets/prompts.

	  	  The Electric Menu

By default all items in the ${mode}electrics array are inserted into a new 
menu.  This allows you to insert them, and get a feel for a small number 
of the completions which exist.  Also at the bottom of the menu are items 
for each of the standard key bindings these routines use, to help you to 
remember them.

	  	  Completion feedback

Help me to help you!

Completions for some common items just don't currently exist.  So if you 
try to complete something and it doesn't work, why not write a completion 
for it?  Once you have assembled a few, mail them to me (preferably 
binhex'd, since bullets '' don't travel well by ASCII mail).  I'd
particularly like completions for other modes.

	  	  Speed

Alpha has some limitations which means some aspects of Vince's Additions
are a little bit slow (on low-end machines, at least).

Two things you can do to alleviate this: first, in modes for which Tab (or 
ctrl-j under the alternative bindings) ALWAYS means to go the next template 
stop and never means to indent the current line, define a new mode variable 
'tabNeverIndents' by adding the following line to your "prefs.tcl":
  
	newPref f tabNeverIndents 1 MODE

where 'MODE' is 'TeX', 'Java', 'HTML' or whatever.  You'll need to add one
such line for each relevant mode.
  
================================================================================
